/*
 * Javlov - a Java toolkit for reinforcement learning with multi-agent support.
 * 
 * Copyright (c) 2009 Matthijs Snel
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package net.javlov;

/**
 * Represents any agent that takes Actions in an Environment, based on States
 * that it receives as input. Typically, the State is returned by the Environment
 * after execution of the Agent's Action.
 *
 * @author Matthijs Snel
 * @version 0.2, 16/05/2009
 * @see Action
 * @see Environment
 * @see State
 */
public interface Agent {

	/**
	 * Does one agent step: picks an actions based on the received state, and learns (or not)
	 * from the received reward.
	 * 
	 * Note: the reward received is typically the reward based on the PREVIOUS action of the 
	 * agent, i.e. the reward received while transitioning to this state.
	 * 
	 * @param s the current state
	 * @param reward the reward based on the previous agent action
	 * @return the next action to take
	 */
	public <T> Action doStep( State<T> s, double reward );
	
	/**
	 * Like doStep, but without the reward because in the first step of its life, there will
	 * be no reward yet.
	 * 
	 * @param s the current state
	 * @return the next action to take
	 */
	public <T> Action firstStep( State<T> s );
	
	/**
	 * Gets the agent's policy for choosing actions based on states.
	 * @return the policy.
	 */
	public Policy getPolicy();
	
	/**
	 * Initialises the agent.
	 */
	public void init();
	
	/**
	 * Resets the agent to its, or a, starting state.
	 */
	public void reset();
	
	/**
	 * Sets the agent's policy for choosing actions based on states.
	 * @param p the policy.
	 */
	public void setPolicy(Policy p);
}
